---
title: Color Field
description: A color field allows users to edit a hex color or individual color channel value.
links:
  - label: Aria docs
    href: https://react-spectrum.adobe.com/react-aria/ColorField.html
  - label: Report an issue
    href: https://github.com/mehdibha/dotUI/issues/new/choose
  - label: Edit this page
    href: https://github.com/mehdibha/dotUI/tree/main/content/components/colors/color-field.mdx?plain=1
---

<ComponentPreview
  name="color-field/demos/default"
  preview={`<ColorField label="Color" />`}
/>

## Installation

```package-install
npx shadcn@latest add @dotui/color-field
```

## Anatomy

```tsx
import { ColorField } from "@/components/core/color-field";

<ColorField label="Background" description="Enter a background color." />;
```

```tsx
import { ColorFiedInput, ColorFieldRoot } from "@/components/core/color-field";
import { Description, FieldError, Label } from "@/components/core/field";

<ColorFieldRoot>
  <Label>Background</Label>
  <ColorFieldInput />
  <Description>Enter a background color.</Description>
  <FieldError />
</ColorFieldRoot>;
```

## Controlled

Use the `value` and `onChange` props to control the value of the input.

<ComponentPreview
  name="color-field/demos/controlled"
  preview={`const [color, setColor] = React.useState<Color | null>(parseColor("#7f007f"));
return <ColorField value={color} onChange={setColor} />`}
/>

## Color channel

By default, ColorField allows the user to edit the color as a hex value. When the colorSpace and channel props are provided, ColorField displays the value for that channel formatted as a number instead.Rendering multiple ColorFields together can allow a user to edit a color.

<ComponentPreview
  name="color-field/demos/color-channel"
  preview={`<ColorField label="Hue" colorSpace="hsl" channel="hue" />
  <ColorField label="Saturation" colorSpace="hsl" channel="saturation" />
  <ColorField label="Lightness" colorSpace="hsl" channel="lightness" />`}
/>

## Label

A visual label can be provided for the `ColorField` using the `label` prop or a hidden label using `aria-label` prop.

<ComponentPreview
  name="color-field/demos/label"
  preview={`<ColorField label="Background" placeholder="Visible label" />
<ColorField aria-label="Background" placeholder="Hidden label" />`}
/>

## Description

A description can be supplied to `ColorField` via the `description` prop. The description is always visible unless the `isInvalid` prop is `true` and an error message is provided.

<ComponentPreview
  name="color-field/demos/description"
  preview={`<ColorField label="Color" description="Enter a background color." />`}
/>

## Validation

By default, `ColorField` displays default validation messages provided by the browser. You can customize this using the `errorMessage` prop, which will be displayed when the `isInvalid` prop is set to `true`.

<ComponentPreview
  name="color-field/demos/error-message"
  preview={`<ColorField label="Color" isInvalid errorMessage="Please fill out this field." />`}
/>

## Options

### Size

Use the `size` prop to control the size of the `ColorField`.<br/>
The default variant is `"md"`.

<ComponentPreview
  name="color-field/demos/sizes"
  preview={`<ColorField label="small" size="sm" />
<ColorField label="medium" size="md" />
<ColorField label="large" size="lg" />`}
/>

### Prefix and suffix

To add additional context for the `ColorField`, use the `prefix` and `suffix` props.

<ComponentPreview
  name="color-field/demos/prefix-and-suffix"
  preview={`<ColorField prefix={<PaletteIcon />} />
<ColorField suffix={<PaletteIcon />} />`}
/>

### Disabled

Use the `isDisabled` prop to disable the `ColorField`.

<ComponentPreview
  name="color-field/demos/disabled"
  preview={`<ColorField value={parseColor("rgb(222,70,58)")} isDisabled />`}
/>

### ReadOnly

The `isReadOnly` boolean prop makes the `ColorField`'s text content immutable. Unlike `isDisabled`, the `ColorField` remains focusable and the contents can still be copied.

<ComponentPreview
  name="color-field/demos/read-only"
  preview={`<ColorField label="Color" isReadOnly value="#121212" />`}
/>

### Required

Use the `isRequired` prop to mark the `ColorField` as required.
Use the `necessityIndicator` prop to control the visual style of the required state.

<ComponentPreview
  name="color-field/demos/required"
  preview={`<ColorField label="Color" isRequired />
<ColorField label="Color" isRequired necessityIndicator="icon" />
<ColorField label="Color" isRequired necessityIndicator="label" />
<ColorField label="Color" necessityIndicator="label" />`}
/>

## Composition

If you need to customize things further, you can drop down to the composition level.

<ComponentPreview
  name="color-field/demos/composition"
  preview={`<ColorFieldRoot>
    <Label>Background</Label>
    <ColorFieldInput />
    <Description>Enter a background color.</Description>
    <FieldError />
  </ColorFieldRoot>`}
/>

## API Reference

| Prop                 | Type                                                                                                    | Default    | Description                                                                                                                                                                                                                           |
| -------------------- | ------------------------------------------------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `channel`            | `'hue' \| 'saturation' \| 'brightness' \| 'lightness' \| 'red' \| 'green' \| 'blue' \| 'alpha'`         | -          | The color channel that this field edits. If not provided, the color is edited as a hex value.                                                                                                                                         |
| `colorSpace`         | `'rgb' \| 'hsl' \| 'hsb'`                                                                               | -          | The color space that the color field operates in if a channel prop is provided. If no channel is provided, the color field always displays the color as an RGB hex value.                                                             |
| `isWheelDisabled`    | `boolean`                                                                                               | -          | Enables or disables changing the value with scroll.                                                                                                                                                                                   |
| `value`              | `T`                                                                                                     | -          | The current value (controlled).                                                                                                                                                                                                       |
| `defaultValue`       | `T`                                                                                                     | -          | The default value (uncontrolled).                                                                                                                                                                                                     |
| `isDisabled`         | `boolean`                                                                                               | -          | Whether the input is disabled.                                                                                                                                                                                                        |
| `isReadOnly`         | `boolean`                                                                                               | -          | Whether the input can be selected but not changed by the user.                                                                                                                                                                        |
| `isRequired`         | `boolean`                                                                                               | -          | Whether user input is required on the input before form submission.                                                                                                                                                                   |
| `isInvalid`          | `boolean`                                                                                               | -          | Whether the input value is invalid.                                                                                                                                                                                                   |
| `validate`           | `(value: Color \| null) => ValidationError \| true \| null \| undefined`                                | -          | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead. |
| `autoFocus`          | `boolean`                                                                                               | -          | Whether the element should receive focus on render.                                                                                                                                                                                   |
| `name`               | `string`                                                                                                | -          | The name of the input element, used when submitting an HTML form.                                                                                                                                                                     |
| `validationBehavior` | `'native' \| 'aria'`                                                                                    | `'native'` | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.                                                                        |
| `children`           | `ReactNode \| (values: ColorFieldRenderProps & {defaultChildren: ReactNode \| undefined}) => ReactNode` | -          | The children of the component. A function may be provided to alter the children based on component state.                                                                                                                             |
| `className`          | `string`                                                                                                | -          | The CSS className for the element.                                                                                                                                                                                                    |
| `style`              | `CSSProperties \| (values: ColorFieldRenderProps & {defaultStyle: CSSProperties}) => CSSProperties`     | -          | The inline style for the element. A function may be provided to compute the style based on component state.                                                                                                                           |

| Event                 | Type                                        | Description                                                                                                      |
| --------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `onChange`            | `(isSelected: boolean) => void`             | Handler that is called when the Switch's selection state changes.                                                |
| `onFocus`             | `(e: FocusEvent<Target>) => void`           | Handler that is called when the Switch receives focus.                                                           |
| `onBlur`              | `(e: FocusEvent<Target>) => void`           | Handler that is called when the Switch loses focus.                                                              |
| `onFocusChange`       | `(isFocused: boolean) => void`              | Handler that is called when the Switch's focus status changes.                                                   |
| `onKeyDown`           | `(e: KeyboardEvent) => void`                | Handler that is called when a key is pressed.                                                                    |
| `onKeyUp`             | `(e: KeyboardEvent) => void`                | Handler that is called when a key is released.                                                                   |
| `onCopy`              | `ClipboardEventHandler<HTMLInputElement>`   | Handler that is called when the user copies text.                                                                |
| `onCut`               | `ClipboardEventHandler<HTMLInputElement>`   | Handler that is called when the user cuts text.                                                                  |
| `onPaste`             | `ClipboardEventHandler<HTMLInputElement>`   | Handler that is called when the user pastes text.                                                                |
| `onCompositionStart`  | `CompositionEventHandler<HTMLInputElement>` | Handler that is called when a text composition system starts a new text composition session.                     |
| `onCompositionEnd`    | `CompositionEventHandler<HTMLInputElement>` | Handler that is called when a text composition system completes or cancels the current text composition session. |
| `onCompositionUpdate` | `CompositionEventHandler<HTMLInputElement>` | Handler that is called when a new character is received in the current text composition session.                 |
| `onSelect`            | `ReactEventHandler<HTMLInputElement>`       | Handler that is called when text in the input is selected.                                                       |
| `onBeforeInput`       | `FormEventHandler<HTMLInputElement>`        | Handler that is called when the input value is about to be modified.                                             |
| `onInput`             | `FormEventHandler<HTMLInputElement>`        | Handler that is called when the input value is modified.                                                         |

| Data attribute                                     | Description                                                                  |
| -------------------------------------------------- | ---------------------------------------------------------------------------- |
| `[data-disabled]`                                  | Whether the color field is disabled.                                         |
| `[data-invalid]`                                   | Whether the color field is invalid.                                          |
| `[data-channel="hex \| hue \| saturation \| ..."]` | The color channel that this field edits, or "hex" if no channel prop is set. |
